Skip to main content

Troubleshooting

Common issues when setting up cdx-extensibility-apps (pnpm, Corepack, playgrounds). Widget- and feature-specific questions stay in those FAQs. Forge CLI errors stay in CLI troubleshooting.

If you seeGo to
Still using npm install / npx nx in your FI submission repoExisting FI submission repos (pnpm)
corepack enable EACCES / EPERMCorepack permission denied
command not found: nxpnpm run vs pnpm exec
specifiers in the lockfile don't match / [sync-mobile-sandbox]Sandbox lockfile out of sync

Existing FI submission repos (pnpm)​

Your private FI GitHub repo (Developer Console submissions) now uses pnpm and a root pnpm-lock.yaml, aligned with the cdx-extensibility-apps layout. Do this once after you pull the migrated repo, then use the pnpm commands in the rest of these guides.

  1. Sync the repo — Pull or merge the latest default branch from GitHub. Use the repo your team already migrated; do not re-scaffold.
  2. On your machine — Enable Corepack and pin pnpm 9.15.9. If corepack enable fails, see Corepack permission denied.
  3. In your FI clone — From the repository root, run pnpm run setup (not npm install). Run Nx with pnpm exec nx … instead of npx nx …. See pnpm run vs pnpm exec.
  4. Day to day — Replace npm install with pnpm run setup when you need a clean install; replace npx nx with pnpm exec nx for generate, build, and preview.

Do not run npm install at the FI repo root — it can desync the lockfile and break CI. Do not delete pnpm-lock.yaml. Commit lockfile changes only when you intentionally change dependencies.

If a submission PR fails CI on a frozen lockfile, see CLI troubleshooting — Submission CI failure.

pnpm run vs pnpm exec​

cdx-extensibility-apps uses pnpm. Do not prefix every command with pnpm exec.

PrefixUse forExamples
pnpm runScripts in package.jsonpnpm run setup, pnpm run sync:mobile, pnpm run build -- agent-widget
pnpm exec nxNx CLI (run, generate, start, serve, build a project)pnpm exec nx start mobile-sandbox, pnpm exec nx run generate-mobile-widget

A bare nx works only if the workspace binary is on your PATH. Do not install Nx globally — use pnpm exec nx. If you see command not found: nx, use pnpm exec nx.

Sandbox lockfile out of sync​

Catalog generate (pnpm exec nx run generate-mobile-widget, generate-mobile-feature, generate-mobile-extensions) adds a file: dependency to playground/mobile-sandbox/package.json. The sandbox lockfile does not include that entry yet, so a frozen install fails on purpose.

You may see red output such as Failure reason: specifiers in the lockfile don't match specs in package.json, then [sync-mobile-sandbox] Sandbox lockfile out of sync — running pnpm install.... That probe is expected. Generate (or pnpm exec nx start mobile-sandbox) succeeded when Nx prints the green success line.

Do not run pnpm run ci:mobile until that sync finishes. If you used the offline generator (pnpm exec nx generate @cdx-extensions/widget-template-mobile:...) instead of the catalog wrapper, run pnpm run sync:mobile yourself. Deprecated-subdependency WARN lines during the repair install (glob, inflight, rimraf, uuid) are noise.

Corepack permission denied​

corepack enable writes pnpm shims next to the Node binary. That fails when the prefix is not writable. This is a Node install layout issue, not a cdx-extensibility-apps defect. It applies to local clone/setup, playgrounds, and the Forge CLI managed checkout.

macOS / Linux — Official Node installers often put binaries in /usr/local/bin (root-owned):

Internal Error: EACCES: permission denied, symlink '.../pnpm.js' -> '/usr/local/bin/pnpm'

Windows — The same step fails when Node is under C:\Program Files\nodejs (needs Administrator). The message is usually EPERM or EACCES creating pnpm.cmd (or pnpm.ps1) in that folder, not a /usr/local/bin symlink.

nvm, fnm, volta, nvm-windows, and similar user-owned Node installs typically do not hit this. Do not use sudo corepack enable or an elevated Administrator terminal as the first fix (root- or admin-owned shims mix badly with a later user Node).

Workaround: install the shims in a directory you own, put that directory on PATH ahead of Program Files / /usr/local/bin, then pin pnpm.

Bash
# macOS / Linux
mkdir -p "$HOME/.local/bin"
corepack enable --install-directory "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
corepack prepare pnpm@9.15.9 --activate
pnpm -v

Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc (or ~/.bashrc) so new terminals keep the shim.

# Windows PowerShell
$shimDir = "$env:LOCALAPPDATA\bin"
New-Item -ItemType Directory -Force -Path $shimDir | Out-Null
corepack enable --install-directory $shimDir
$env:Path = "$shimDir;$env:Path"
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($userPath -notlike "*$shimDir*") {
  [Environment]::SetEnvironmentVariable('Path', "$shimDir;$userPath", 'User')
}
corepack prepare pnpm@9.15.9 --activate
pnpm -v

Close and reopen the terminal after the User PATH change (or sign out) so other windows pick it up. Confirm where.exe pnpm lists %LOCALAPPDATA%\bin before C:\Program Files\nodejs.

If you cannot change PATH, skip shims: corepack prepare pnpm@9.15.9 --activate, then prefix commands with corepack (corepack pnpm run setup, corepack pnpm exec nx …).